% !TEX TS-program = pdflatex
% !TEX encoding = UTF-8 Unicode

% This is a simple template for a LaTeX document using the "article" class.
% See "book", "report", "letter" for other types of document.

\documentclass[11pt]{article} % use larger type; default would be 10pt

\usepackage[utf8]{inputenc} % set input encoding (not needed with XeLaTeX)

%%% Examples of Article customizations
% These packages are optional, depending whether you want the features they provide.
% See the LaTeX Companion or other references for full information.

%%% PAGE DIMENSIONS
\usepackage{geometry} % to change the page dimensions
\geometry{a4paper} % or letterpaper (US) or a5paper or....
% \geometry{margin=2in} % for example, change the margins to 2 inches all round
% \geometry{landscape} % set up the page for landscape
%   read geometry.pdf for detailed page layout information

\usepackage{graphicx} % support the \includegraphics command and options

% \usepackage[parfill]{parskip} % Activate to begin paragraphs with an empty line rather than an indent

%%% PACKAGES
\usepackage{booktabs} % for much better looking tables
\usepackage{array} % for better arrays (eg matrices) in maths
\usepackage{paralist} % very flexible & customisable lists (eg. enumerate/itemize, etc.)
\usepackage{verbatim} % adds environment for commenting out blocks of text & for better verbatim
\usepackage{subfig} % make it possible to include more than one captioned figure/table in a single float
% These packages are all incorporated in the memoir class to one degree or another...

%%% HEADERS & FOOTERS
\usepackage{fancyhdr} % This should be set AFTER setting up the page geometry
\pagestyle{fancy} % options: empty , plain , fancy
\renewcommand{\headrulewidth}{0pt} % customise the layout...
\lhead{}\chead{}\rhead{}
\lfoot{}\cfoot{\thepage}\rfoot{}

%%% SECTION TITLE APPEARANCE
\usepackage{sectsty}
\allsectionsfont{\sffamily\mdseries\upshape} % (See the fntguide.pdf for font help)
% (This matches ConTeXt defaults)

%%% ToC (table of contents) APPEARANCE
\usepackage[nottoc,notlof,notlot]{tocbibind} % Put the bibliography in the ToC
\usepackage[titles,subfigure]{tocloft} % Alter the style of the Table of Contents
\renewcommand{\cftsecfont}{\rmfamily\mdseries\upshape}
\renewcommand{\cftsecpagefont}{\rmfamily\mdseries\upshape} % No bold!

%%% END Article customizations

%%% The "real" document content comes below...

\title{Project Report}
\author{Francesco Rosso - Matr. 592057}
\date{August 2012}

\begin{document}
\maketitle

\begin{abstract}
The concurrent and distributed Java application to be developed is divided in two main parts:
\begin{description}
\item[server:] should be able to store in a txt file the results collected by the clients connected in the current session, one result for each line
\item[client:] should be able to run (at least) a single simulation accordingly to the information stored in a configuration file and send the information about the simulation to the server. \\
Every simulation consists in the creation of \texttt{n} nodes. Each node is identified by a name ( \texttt{id} ) and a position, and should be able to communicate with his neighbours that are located around his communication radius \texttt{r}. Each node has a certain amount of energy, that is used to perform some operations (i.e. message sending, signature checks, etc).\\
Between those nodes there is a clone. A clone is a node that has the same \texttt{id} of another node, but is placed in another position.\\
Running the protocol specified in the configuration file, the nodes should be able to locate the clone.
\end{description}
\end{abstract}

\section{Application compilation and running}
It has been included a \texttt{readme.txt} file where there are written all the operations to compile and run both client and server application.

\section{Design overview}
This application implements the MVC design pattern to separate data structures from graphics in the client's UI. So, the application is divided in packages.
\begin{description}
\item[\texttt{pcd112.model.eccezioni}:] this package contains all the exceptions needed in the program execution. \\
The most important of these exceptions is \texttt{ErrorException}, that stores an exception message and its detailed description.
\item[\texttt{pcd1112.mode.messaggi}:] this package contains all the messages that could be forwarded between nodes.\\
\texttt{MessaggioBase} is the message's skeleton class, but it can't be forwarded by nodes. \texttt{MessaggioUnicast} and \texttt{MessaggioBroadcast} extends \texttt{MessaggioBase} and represents respectively a message that can be forwarded between nodes and a message that can be sent by a node in its broadcast (radius).
\item[\texttt{pcd112.model}:] in this package are stored all the classes that represents data and business rules. All the data classes needed to perform a single simulation are stored in this package. This package contains both client and server's classes.\\
\begin{description}
\item[\texttt{Nodo}:] represents a single node needed in a simulation. Implements \texttt{INodo} and \texttt{Runnable} interfaces, because each node is a single thread in the application.
\item[\texttt{Ambiente}:] represents the environment in which nodes can exchange messages. It implements the \texttt{Singleton} design pattern, as it should be unique in the simulation process and it should be reachable in the vast majority of the classes.
\item[\texttt{Config}:] implements the \texttt{Singleton} design pattern and represents the configuration file.
\item[\texttt{Coordinata}:] represents a single point in the unit-square area, where nodes are placed.
\item[\texttt{Hypervisor}:] the Hypervisor class will set up the simulation. It initialize the unit-square area with the right number of nodes, placing them in a random position, insert a clone, starts a single simulation and sends the result to the server.
\item[\texttt{AwaitStop}:] this class has a single static method. When called, the method will active wait until all the nodes provided are in a waiting or terminated state. It does so by creating a new thread that will be continuously checking them.
\item[\texttt{TxtWriterImpl}:] this class is needed by the RMI server to store in the \texttt{output.txt} file what the clients send.
\end{description}
\item[\texttt{pcd1112.controller}:] this package contain the \texttt{Controller} class, that mediates the user input and provides a graphical representations of the data modelled. It implements the \texttt{ActionListener} interface to support the user input. The \texttt{Simulations} nested class, that is effectively a Thread, will perform the operations on the model and it partially changes the GUI behaviour.
\item[\texttt{pcd1112.view}:] this package contains a couple of classes. The most important of them is \texttt{ClientGUI}, that represents the Client main UI.\\
\texttt{PannelloNodi} is just a Panel to be added to \texttt{ClientGUI}. It has a nested class that implements the Observer interface, needed to be informed on a node state change.
\end{description}

\section{Design issues}
The main quality aspects in this application are code efficiency, extendability and stability. Unit tests and integration tests has been executed on the most critical program's parts.

\subsection{Stability}
Stability is provided by the avoidance of deadlocks. Each node can communicate with his neighbours in an independent way.

\subsection{Extendability}
We can easily extend the \texttt{MessaggioBase} class to add different types of messages, that could have different types of behaviours in a node. \\
An example is provided by \texttt{pcd1112.model.messaggi.MessaggioTesto} class, that allows nodes to exchange simple text messages.

\subsection{Efficiency}
During the development process some efficiency tests have been performed.\\
The biggest design flaw is the \texttt{AwaitStop} class requirement. In each simulation, it continuously cycles through all the nodes until they all are in a terminated or waiting state. And it waste some CPU cycles.
\paragraph{Node class efficiency}
Internal messages storing and searching has been improved by the use of \texttt{Map} instead of \texttt{ArrayList}. Using \texttt{Map}, storing and (above all) searching is done in constant time.\\
The first implementation of the node class, provided that the nodes should build their own maps of their neighbourhood broadcasting a special message and looking for responses. With an high number of nodes (e.g. more than 1000) this becomes inefficient. So the client GUI provides an option to select this mode (that is called "real") or the default one, in which  \texttt{Ambiente} builds the node's neighbourhood every time a node is added.

\subsection{Other}
In a first implementation, \texttt{Nodo} class extended \texttt{Thread} instead of  \texttt{Observable} and implemented only \texttt{INodo}. \texttt{Observable} was added to allow the GUI to know when a node state is changed. This feature has resulted in a modification of \texttt{Nodo} internal class representation.\\
Also, \texttt{Nodo} didn't have  \texttt{isClone()}, \texttt{setClone(boolean}, \texttt{iscloned()} and \texttt{setCloned(boolean)} methods, but they become useful in the GUI design, to easily identify clone and cloned nodes.\\
\texttt{Ambiente} (and so the GUI) didn't allow the user to pause and resume the current simulation. Adding this featured has cost adding an extra synchronization object in \texttt{Ambiente}, checking for the pause state variable on every message exchange and an extra flag check in the \texttt{AwaitStop} class. \\
Probably the \texttt{AwaitStop} class could be a little improved adding the \texttt{Observer} extension, and the \texttt{Observable} implementation to \texttt{Ambiente}, so it can pause checking for nodes in a waiting state when also the \texttt{Ambiente} is in a pause state.\\

\section{Design choices}
\texttt{Config} class implements the \texttt{Singleton} GOF's design pattern because a \texttt{Config} object should be reachable in various program parts. The same thing applies to the \texttt{Ambiente} class.\\
The \texttt{Config} class uses the \texttt{Properties}'s Java parser, because the syntax needed to parse the configuration file is identical and writing another custom parsing class would be revealed inefficient and a waste of time.\\
The first implementation of the node class, provided that the nodes should build their own maps of their neighbourhood broadcasting a special message and looking for responses. With an high number of nodes (e.g. more than 1000) this becomes inefficient. So the client GUI provides an option to select this mode (that is called "real") or the default one, in which is the \texttt{Ambiente} to build the node's neighbourhood every time a node is added. The exchange of these types of messages does not affect the node's energy.\\
The existence of \texttt{Ambiente} has both pro and cons. It surely affects the program's performance slowing it down a little bit, but it also keeps the program more readable and closer to the reality, because a single node doesn't broadcasts a message cycling through all his neighbours, but it will send a single message to his broadcast, spending a single amount of energy.\\
Another aspect I thought of, is if a single node should warn his neighbours when he is dead or if a node should continuously check if his neighbours are still alive. According to reality, a node has no way of knowing when his batteries will be dead. And continuously checking for dead nodes is a waste of energy, because each node should send a message to all his neighbours and wait for an answer.\\
Another aspect was adding the possibility to the user to manually insert each parameter of the configuration file, in case the configuration file's server was down. But my Java's AWT knowledge is not enough to add this feature in a decent amount of time.

\section{Extra features}
\begin{itemize}
\item Client GUI allows to select between real or default node neighbourhood creation
\item Client GUI allows the user to pause/resume/stop the current simulation
\item Client GUI allows the user to specify the amount of time each node has to wait before computing the received message in real time, through a slider or direct input
\item Client GUI allows the user to have a graphical representation of the nodes, highlighting clone and cloned nodes
\item Client GUI allows the user to click on a specified node and see his information in real time
\item Client GUI allows the user to see the current simulation number through a progress bar
\end{itemize}

\end{document}
